d3plus-geomap

d3plus-geomap

A reusable geo map built on D3 and Topojson

Installing

If you use NPM, run npm install d3plus-geomap --save. Otherwise, download the latest release. The released bundle supports AMD, CommonJS, and vanilla environments. You can also load directly from d3plus.org:

<script src="https://d3plus.org/js/d3plus-geomap.v0.5.full.min.js"></script>

Simple Choropleth Map

D3plus makes it really easy to create choropleth maps. Let's make one using a dataset that includes US state ids and population estimates:

var popData = [{id: "01", population: 4830620}, {id: "02", population: 733375}, {id: "04", population: 6641928}, {id: "05", population: 2958208}, {id: "06", population: 38421464}, {id: "08", population: 5278906}, {id: "09", population: 3593222}, {id: "10", population: 926454}, {id: "11", population: 647484}, {id: "12", population: 19645772}, {id: "13", population: 10006693}, {id: "15", population: 1406299}, {id: "16", population: 1616547}, {id: "17", population: 12873761}, {id: "18", population: 6568645}, {id: "19", population: 3093526}, {id: "20", population: 2892987}, {id: "21", population: 4397353}, {id: "22", population: 4625253}, {id: "23", population: 1329100}, {id: "24", population: 5930538}, {id: "25", population: 6705586}, {id: "26", population: 9900571}, {id: "27", population: 5419171}, {id: "28", population: 2988081}, {id: "29", population: 6045448}, {id: "30", population: 1014699}, {id: "31", population: 1869365}, {id: "32", population: 2798636}, {id: "33", population: 1324201}, {id: "34", population: 8904413}, {id: "35", population: 2084117}, {id: "36", population: 19673174}, {id: "37", population: 9845333}, {id: "38", population: 721640}, {id: "39", population: 11575977}, {id: "40", population: 3849733}, {id: "41", population: 3939233}, {id: "42", population: 12779559}, {id: "44", population: 1053661}, {id: "45", population: 4777576}, {id: "46", population: 843190}, {id: "47", population: 6499615}, {id: "48", population: 26538614}, {id: "49", population: 2903379}, {id: "50", population: 626604}, {id: "51", population: 8256630}, {id: "53", population: 6985464}, {id: "54", population: 1851420}, {id: "55", population: 5742117}, {id: "56", population: 579679}, {id: "72", population: 3583073}];

After initializing a new Geomap instance, we need to pass our popData array to the data method and tell colorScale which key in our data array to use as the basis for the color scale:

var chart = new d3plus.Geomap()
  .data(popData)
  .colorScale("population");

Choropleth maps need an additional data type in order to correctly shade geographical boundaries: Topojson. Topojson files are a JSON-type file that include web-optimized (ie. small filesize) boundaries for a given set of geographies. For this example, we need to use a topojson file for the United States. Topojson files can be created from Shapefiles or GeoJSON using various websites and the command-line tools made available by the creators of the format.

Topojson files also include meta information (usually stored as "properties") that help us match our data to the specific geographical boundaries. If each of the objects in your Topojson include an id property that matches your data array, then you're good to go!

Additionally, Topojson files may include small geographies that negatively impact how the library determines the default zoom level (for example, a small island or territory far off the coast that is barely visible to the eye). We can use the fitFilter method to remove specific geographies from the logic used to determine the zooming, in this case removing small islands, like Guam and American Samoa, and removing Alaska in order to focus on the 48 contiguous US states.

chart
  .topojson("https://d3plus.org/topojson/states.json")
  .fitFilter(function(d) {
    return ["02", "15", "43", "60", "66", "69", "72", "78"].indexOf(d.id) < 0;
  });

Once those 2 pieces are configured (data and Topojson), we are ready to render the visualization:

chart.render();

Click here to view this example live on the web.

More Examples

• Income by Census Tract
• Changing Map Projections
• Resetting Defaults
• Changing the Geo Map Tiles
• Choropleth w/ Custom Colors
• Coordinate Points on a Map
• Choropleth w/ Jenks Breaks

API Reference

• Geomap

---

Geomap <>

This is a global class, and extends all of the methods and functionality of Viz.

• Geomap ⇐ Viz
  • new Geomap()
  • .fitFilter([value]) ↩︎
  • .fitKey(value) ↩︎
  • .fitObject(data, [formatter]) ↩︎
  • .ocean([value]) ↩︎
  • .point([value]) ↩︎
  • .pointSize([value]) ↩︎
  • .pointSizeMax([value]) ↩︎
  • .pointSizeMin([value]) ↩︎
  • .projection(projection) ↩︎
  • .projectionPadding([value]) ↩︎
  • .tiles([value]) ↩︎
  • .tileUrl([url]) ↩︎
  • .topojson(data, [formatter]) ↩︎
  • .topojsonFilter([value]) ↩︎
  • .topojsonKey(value) ↩︎
  • .topojsonId(value) ↩︎

# new Geomap()

Creates a geographical map with zooming, panning, image tiles, and the ability to layer choropleth paths and coordinate points. See this example for help getting started.

# Geomap.fitFilter([value]) <>

Topojson files sometimes include small geographies that negatively impact how the library determines the default zoom level (for example, a small island or territory far off the coast that is barely visible to the eye). The fitFilter method can be used to remove specific geographies from the logic used to determine the zooming.

The value passed can be a single id to remove, an array of ids, or a filter function. Take a look at the Choropleth Example to see it in action.

This is a static method of Geomap, and is chainable with other methods of this Class.

# Geomap.fitKey(value) <>

If the topojson being used to determine the zoom fit (either the main topojson object or the fitObject) contains multiple geographical sets (for example, a file containing state and county boundaries), use this method to indentify which set to use for the zoom fit.

If not specified, the first key in the Array returned from using Object.keys on the topojson will be used.

This is a static method of Geomap, and is chainable with other methods of this Class.

# Geomap.fitObject(data, [formatter]) <>

The topojson to be used for the initial projection fit extent. The value passed should either be a valid Topojson Object or a String representing a filepath or URL to be loaded.

Additionally, a custom formatting function can be passed as a second argument to this method. This custom function will be passed the data that has been loaded, as long as there are no errors. This function needs to return the final Topojson Object.

This is a static method of Geomap, and is chainable with other methods of this Class.

Param	Type	Description
data	Object | String	= undefined
[formatter]	function

# Geomap.ocean([value]) <>

The color visible behind any shapes drawn on the map projection. By default, a color value matching the color used in the map tiles is used to help mask the loading time needed to render the tiles. Any value CSS color value may be used, including hexidecimal, rgb, rgba, and color strings like "blue" and "transparent".

This is a static method of Geomap, and is chainable with other methods of this Class.

# Geomap.point([value]) <>

The accessor to be used when detecting coordinate points in the objects passed to the data method. Values are expected to be in the format [longitude, latitude], which is in-line with d3's expected coordinate mapping.

This is a static method of Geomap, and is chainable with other methods of this Class.

# Geomap.pointSize([value]) <>

The accessor or static value to be used for sizing coordinate points.

This is a static method of Geomap, and is chainable with other methods of this Class.

# Geomap.pointSizeMax([value]) <>

The maximum pixel radius used in the scale for sizing coordinate points.

This is a static method of Geomap, and is chainable with other methods of this Class.

# Geomap.pointSizeMin([value]) <>

The minimum pixel radius used in the scale for sizing coordinate points.

This is a static method of Geomap, and is chainable with other methods of this Class.

# Geomap.projection(projection) <>

Sets the map projection used when displaying topojson and coordinate points. Any of the standard projections exported from d3-geo are accepted, whether as the string name (ie. "geoMercator") or the generator function itself. Map tiles are only usable when the projection is set to Mercator (which is also the default value).

This is a static method of Geomap, and is chainable with other methods of this Class.

# Geomap.projectionPadding([value]) <>

The outer padding between the edge of the visualization and the shapes drawn. The value passed can be either a single number to be used on all sides, or a CSS string pattern (ie. "20px 0 10px").

This is a static method of Geomap, and is chainable with other methods of this Class.

# Geomap.tiles([value]) <>

Toggles the visibility of the map tiles.

This is a static method of Geomap, and is chainable with other methods of this Class.

# Geomap.tileUrl([url]) <>

By default, d3plus uses the light_all style provided by CARTO for it's map tiles. The tileUrl method changes the base URL used for fetching the tiles, as long as the string passed contains {x}, {y}, and {z} variables enclosed in curly brackets for the zoom logic to load the correct tiles.

This is a static method of Geomap, and is chainable with other methods of this Class.

# Geomap.topojson(data, [formatter]) <>

The topojson to be used for drawing geographical paths. The value passed should either be a valid Topojson Object or a String representing a filepath or URL to be loaded.

Additionally, a custom formatting function can be passed as a second argument to this method. This custom function will be passed the data that has been loaded, as long as there are no errors. This function should return the final Topojson Obejct.

This is a static method of Geomap, and is chainable with other methods of this Class.

Param	Type	Description
data	Object | String	= []
[formatter]	function

# Geomap.topojsonFilter([value]) <>

If the topojson being used contains boundaries that should not be shown, this method can be used to filter them out of the final output. The value passed can be a single id to remove, an array of ids, or a filter function.

This is a static method of Geomap, and is chainable with other methods of this Class.

# Geomap.topojsonKey(value) <>

If the topojson contains multiple geographical sets (for example, a file containing state and county boundaries), use this method to indentify which set to use.

If not specified, the first key in the Array returned from using Object.keys on the topojson will be used.

This is a static method of Geomap, and is chainable with other methods of this Class.

# Geomap.topojsonId(value) <>

The accessor used to map each topojson geometry to it's corresponding data point.

This is a static method of Geomap, and is chainable with other methods of this Class.

---

_{Documentation generated on Fri, 14 Sep 2018 16:00:27 GMT}